Description

Follow-up to #28815 (Phase 2 automated collection).

Rewrites the AI tool usage collection system to use a local CSV append log instead of direct SQLite writes from hooks. The root cause driving the change: the hook shell environment does not honour .nvmrc, so hooks were running against the system Node rather than the project's pinned version — making better-sqlite3 bindings unreliable. The fix decouples write-time from read-time: hooks now do a pure-shell printf >> file (zero Node dependency), and the SQLite DB will be populated on-demand by dev-tooling-explorer or the future cron.

What changed:

• Architecture: Hooks now append one CSV row to ~/.tool-usage-collection/metamask-mobile-events.log. The SQLite DB is populated on-demand by dev-tooling-explorer or the nightly cron — not by the hooks themselves.
• Pure-shell hooks: Replaced all Node/tsx/SQLite hook infrastructure with two tiny shell entry scripts (hook-cursor-dispatch.sh, hook-claude-dispatch.sh) and a shared hook-common.sh. No Node, no yarn, no subprocess spawning in the hook path.
• Split dispatchers: Cursor and Claude each have their own entry script. hook-cursor-dispatch.sh unconditionally emits {"permission":"allow"} as its first line (before any CI/opt-out check) so tool use is never blocked regardless of tracking state.
• Cursor slash-command tracking (Path 4): Added hook-cursor-prompt-dispatch.sh on the beforeSubmitPrompt event. When a user invokes a skill via a slash command (e.g. /mms-pr-changelog), Cursor injects the skill content directly into the prompt context without the agent reading a SKILL.md file — so the existing preToolUse path never fires. This hook intercepts the raw prompt, extracts the skill name, and appends one CSV row. The {"permission":"allow"} response is always emitted first.
• Fast-exit guard: The CI/opt-out guard runs before reading stdin in both hook-common.sh and hook-cursor-prompt-dispatch.sh — no unnecessary cat on opted-out runs.
• False-positive fix: Path-based skill detection is now gated on the tool being a file-read tool (ReadFile/Read) — prevents StrReplace and other tools carrying skill paths as string content from generating spurious log entries.
• CSV header: Log files are self-describing — a header row is written on first creation.
• .claude/settings.json: Project-level PreToolUse hook on the Skill tool (replaces per-skill frontmatter hooks). Zero per-skill boilerplate.
• Removed: db.ts, events.ts, tool-usage-collection.ts, cursor-hook-skill-tracking.ts, better-sqlite3 dependency, @types/better-sqlite3.
• Tests: Full Jest coverage for all three dispatcher scripts (via child_process.execFileSync) and the Yarn plugin's CSV append path. Test file renamed from hook-skill-tracking-dispatch.test.ts to hook-dispatchers.test.ts to match the actual scripts.
• Docs: Updated scripts/tooling/README.md with new architecture diagram (all 4 collection paths) and AGENTS.md collection-path table.

Changelog

CHANGELOG entry: null

Related issues

Refs: MCWP-513

Manual testing steps

Feature: CSV log-based skill tracking for Cursor and Claude

  Background:
    Given the branch is checked out and dependencies are installed with `yarn install`
    And Claude Code and Cursor are configured with this repo as the working directory
    And Common skills are installed from https://github.com/Consensys/skills

  Scenario: Cursor hook tracks a skill activation via agent read and never blocks tool use
    Given the log file does not exist at ~/.tool-usage-collection/metamask-mobile-events.log
    When the user prompts Cursor with "what's the changelog for this PR?"
    Then a new row appears in the log with tool_name="skill:mms-pr-changelog" and agent_vendor="cursor"
      # verify: tail -5 ~/.tool-usage-collection/metamask-mobile-events.log
    And Cursor tool use was not blocked

  Scenario: Cursor slash-command tracking via beforeSubmitPrompt hook
    When user types "/mms-pr-changelog" in a Cursor chat and submits it
    Then a new row appears in the log with tool_name="skill:mms-pr-changelog" and agent_vendor="cursor"
    # verify: tail -5 ~/.tool-usage-collection/metamask-mobile-events.log
    And the prompt submission was not blocked

  Scenario: Cursor hook still emits allow when CI is set or user is opted out
    Given CI=true is exported in the shell (or TOOL_USAGE_COLLECTION_OPT_IN=false)
    When the user prompts Cursor with "what's the changelog for this PR?"
    Then no new rows are written to the log
    # verify: tail -5 ~/.tool-usage-collection/metamask-mobile-events.log
    And the hook exits 0 without blocking Cursor

  Scenario: Claude Code global hook tracks a skill activation
    Given CI and TOOL_USAGE_COLLECTION_OPT_IN are reset/removed since previous test
    When user starts a Claude Code session
    And the user prompts Claude with "what's the changelog for this PR?"
    Then a new row appears with tool_name="skill:mms-pr-changelog" and agent_vendor="claude"
    # verify: tail -5 ~/.tool-usage-collection/metamask-mobile-events.log

  Scenario: Yarn script tracking
    When user runs `yarn lint`
    Then start and end rows appear in the log for that script
    # verify: tail -5 ~/.tool-usage-collection/metamask-mobile-events.log

  Scenario: Yarn script tracking interrupted
    When user runs `yarn lint`
    And cancels the lint run with `ctrl+C`
    Then start and interrupted rows appear in the log for that script
    # verify: tail -5 ~/.tool-usage-collection/metamask-mobile-events.log

Screenshots/Recordings

Before

N/A

After

Log file should look like the following:

$ tail -5 ~/.tool-usage-collection/metamask-mobile-events.log
tool_name,tool_type,event_type,agent_vendor,session_id,success,duration_ms,created_at
skill:mms-pr-changelog,skill,start,cursor,sess-123,,,2026-05-04T13:37:10Z
skill:mms-pr-changelog,skill,start,cursor,sess-456,,,2026-05-04T13:37:42Z
skill:mms-pr-changelog,skill,start,claude,sess-789,,,2026-05-04T13:37:51Z
yarn:lint,yarn_script,start,,,,,2026-05-04T13:38:10Z
yarn:lint,yarn_script,end,,,,120000,2026-05-04T13:40:10Z
yarn:lint,yarn_script,start,,,,,2026-05-04T13:50:10Z
yarn:lint,yarn_script,interrupted,,,,5000,2026-05-04T13:50:20Z

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.